Github Release

Description

This plugin enables the ability to manage GitHub releases GitHub CLI in a Vela pipeline.

Source Code: https://github.com/go-vela/vela-github-release

Registry: https://hub.docker.com/r/target/vela-github-release

Usage

NOTE:

Users should refrain from using latest as the tag for the Docker image.

It is recommended to use a semantically versioned tag instead.

Sample of creating a GitHub release:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: create
      files: [ gh/common, gh/dev/deploy.yml ]
      tag: v0.1.0

Sample of creating a GitHub release, attaching all .pdf files in the current directory:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: create
      files: [ "*.pdf" ]
      tag: v0.1.0

[!IMPORTANT] This uses Go's implementation of glob patterns

Sample of deleting release files:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: delete
      tag: v0.1.0

Sample of downloading assets from a release in a project:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: download
      tag: v0.1.0

Sample of listing releases in a repository:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: list

Sample of uploading assets to a gh release:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: upload
      files: [ changelog.md ]
      tag: v0.1.0

Sample of uploading assets using glob pattern to a gh release:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: upload
      files: [ "*.pdf" ]
      tag: v0.1.0

[!IMPORTANT] This uses Go's implementation of glob patterns

Sample of viewing information about a gh release:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: view
      tag: v0.1.0

Secrets

NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.

Internal

The plugin accepts the following parameters for authentication:

Parameter	Environment Variable Configuration
`token`	`PARAMETER_TOKEN`, `CONFIG_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`

Users can use Vela internal secrets to substitute these sensitive values at runtime:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
+   secrets: [github_token]
    parameters:
      action: create
      files: [ gh/common, gh/dev/deploy.yml ]

This example will add the secrets to the gh step as environment variables:

GITHUB_TOKEN=<value>

External

The plugin accepts the following files for authentication:

Parameter	Volume Configuration
`token`	`/vela/parameters/github-release/config/token`, `/vela/secrets/github-release/config/token`

Users can use Vela external secrets to substitute these sensitive values at runtime:

steps:
  - name: gh
    image: target/vela-github-release:latest
    pull: always
+   secrets: [github_token]
    parameters:
      config:
-       github_token: somepersonalaccesstoken

This example will read the secret value in the volume stored at /vela/secrets/

Parameters

NOTE:

The plugin supports reading all parameters via environment variables or files.

VELA environments can be found at VELA Environments

Any values set from a file take precedence over values set from the environment.

The following parameters are used to configure the image:

Name	Description	Required	Default	Environment Variables
`action`	action to perform against gh	`true`	`N/A`	`PARAMETER_ACTION` `CONFIG_ACTION`
`hostname`	hostname to set for GitHub instance	`true`	`github.com`	`PARAMETER_HOSTNAME` `GH_HOST` `GITHUB_HOST`
`token`	token to set to authenticate to GitHub instance	`true`	`N/A`	`PARAMETER_TOKEN` `CONFIG_TOKEN` `GH_TOKEN` `GITHUB_TOKEN`
`log_level`	set the log level for the plugin	`true`	`info`	`PARAMETER_LOG_LEVEL` `VELA_LOG_LEVEL` `GITHUB_RELEASE_LOG_LEVEL`
`version`	version of the `gh` CLI to install	`false`	`v2.14.4`	`PARAMETER_VERSION` `VELA_GH_VERSION` `GH_VERSION`

Create

The following parameters are used to configure the create action:

Name	Description	Required	Default	Environment Variables
`draft`	save the release as a draft instead of publishing it	`false`	`false`	`PARAMETER_DRAFT` `CREATE_DRAFT`
`notes`	create release notes	`false`	`N/A`	`PARAMETER_NOTES` `CREATE_NOTES`
`notes_file`	read release notes from file	`false`	`N/A`	`PARAMETER_NOTES_FILE` `CREATE_NOTES_FILE`
`files`	file(s) name used to create	`false`	`N/A`	`PARAMETER_FILES` `GITHUB_RELEASE_FILES`
`prerelease`	mark the release as a prerelease	`false`	`false`	`PARAMETER_PRERELEASE` `CREATE_PRERELEASE`
`tag`	github tag name to create	`true`	`N/A`	`PARAMETER_TAG` `GITHUB_RELEASE_TAG`
`target`	target branch or commit SHA	`true`	`main`	`PARAMETER_TARGET` `CREATE_TARGET`
`title`	Release title	`false`	`N/A`	`PARAMETER_TITLE` `CREATE_TITLE`

Delete

The following parameters are used to configure the delete action:

Name	Description	Required	Default	Environment Variables
`yes`	skip the delete confirmation prompt	`false`	`false`	`PARAMETER_YES` `DELETE_YES`
`tag`	github tag name to delete	`true`	`N/A`	`PARAMETER_TAG` `GITHUB_RELEASE_TAG`

Download

The following parameters are used to configure the download action:

Name	Description	Required	Default	Environment Variables
`directory`	the directory to download files	`true`	`"."`	`PARAMETER_DIR` `DOWNLOAD_DIR`
`patterns`	download only assets that match glob patterns	`false`	`N/A`	`PARAMETER_PATTERNS` `DOWNLOAD_PATTERNS`
`tag`	github tag name to download	`true`	`N/A`	`PARAMETER_TAG` `GITHUB_RELEASE_TAG`

List

The following parameters are used to configure the list action:

Name	Description	Required	Default	Environment Variables
`limit`	maximum number of items to fetch for list action	`true`	`30`	`PARAMETER_LIMIT` `LIST_LIMIT`

Upload

The following parameters are used to configure the upload action:

Name	Description	Required	Default	Environment Variables
`clobber`	overwrite existing assets of the same name	`false`	`false`	`PARAMETER_CLOBBER` `UPLOAD_CLOBBER`
`files`	file(s) name used to upload	`true`	`N/A`	`PARAMETER_FILES` `GITHUB_RELEASE_FILES`
`tag`	github tag name to upload	`true`	`N/A`	`PARAMETER_TAG` `GITHUB_RELEASE_TAG`

View

The following parameters are used to configure the view action:

Name	Description	Required	Default	Environment Variables
`tag`	github tag name to view	`true`	`N/A`	`PARAMETER_TAG` `GITHUB_RELEASE_TAG`
`web`	open the release in the browser	`true`	`false`	`PARAMETER_WEB` `VIEW_WEB`

Troubleshooting

You can start troubleshooting this plugin by tuning the level of logs being displayed:

steps:
  - name: github-release
    image: target/vela-github-release:latest
    pull: always
    parameters:
      action: create
      files: [ gh/common, gh/dev/deploy.yml ]
+     log_level: trace

Description​

Usage​

Secrets​

Internal​

External​

Parameters​

Create​

Delete​

Download​

List​

Upload​

View​

Troubleshooting​